Docs: split builtins to their own page from library by nedbat · Pull Request #156682 · python/cpython

nedbat · 2026-08-30T20:07:36Z

We've talked about separating the built-ins from the stdlib modules, since "dict" (for example) isn't part of the stdlib.

I think I took care of all the places the pages are referenced, but the non-HTML builds are new to me, so I might have missed something.

I tried to make the intro paragraphs and pages useful, and avoided over-editing them.

nedbat · 2026-08-30T20:11:51Z

Also: is this NEWS-worthy?

StanFromIreland · 2026-08-30T20:12:50Z

Also: is this NEWS-worthy?

I don't see a need for one here, I think the docs speak for themselves.

read-the-docs-community · 2026-08-30T20:14:40Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #34500006 | 📁 Comparing 016ce6b against main (852381e)

🔍 Preview build

72 files changed · + 7 added · ± 65 modified

+ Added

± Modified

hugovk

Shall we name the new Doc/library/builtin-index.rst as Doc/builtins/index.rst instead?

Then instead of:

https://docs.python.org/3/library/builtins-index.html

We get a neater:

This PR can still reference the builtin stuff in their current location, and a followup could move the relevant files and deal with redirects:

Doc/library/functions.rst -> Doc/builtins/functions.rst
Doc/library/stdtypes.rst -> Doc/builtins/stdtypes.rst
Doc/library/constants.rst -> Doc/builtins/constants.rst
Doc/library/exceptions.rst -> Doc/builtins/exceptions.rst
Doc/library/threadsafety.rst -> Doc/builtins/threadsafety.rst
Doc/library/time-complexity.rst -> Doc/builtins/time-complexity.rst

StanFromIreland

Also, you need to update the What Now? page in the tutorial.

I concur with Hugo, splitting this into a separate directory would be nicer. We can do redirects at client side (using one of the various Sphinx extensions) or sever side (by configuring them in python/psf-salt).

nedbat · 2026-08-31T17:55:49Z

I can do the renames and redirects.

We can do redirects at client side (using one of the various Sphinx extensions) or sever side (by configuring them in python/psf-salt).

What Sphinx extension have we used for redirects before? I see https://github.com/python/psf-salt/blob/main/salt/docs/config/nginx.docs-redirects.conf for the psf-salt approach.

StanFromIreland · 2026-08-31T18:17:41Z

What Sphinx extension have we used for redirects before?

We use sphinxext-rediraffe in the Devguide, it generates stubs with some JS to redirect to the new page.

nedbat · 2026-08-31T18:26:52Z

What Sphinx extension have we used for redirects before?

We use sphinxext-rediraffe in the Devguide, it generates stubs with some JS to redirect to the new page.

I knew rediraffe was somewhere! Is there a reason we don't want to introduce it for the main docs?

StanFromIreland · 2026-08-31T18:30:35Z

Is there a reason we don't want to introduce it for the main docs?

I presume it's simply because there hasn't really been a need so far. We're less keen to move pages here than in the Devguide. IIRC rediraffe requires JS, but that ship has sailed anyway.

hugovk · 2026-09-01T11:16:14Z

Server-side psf-salt redirects would be better than client-side sphinxext-rediraffe: they work with JavaScript disabled (better for all the scrapers and bots), are faster on server-side (HTTP layer before any HTML fetched), and get cached in the CDN, and better for SEO.

We don't have such server-side control for the devguide, which is hosted on GitHub Pages. (Also I'd say client-side JS redirects are fine for the less-important devguide.)

nedbat · 2026-09-01T12:50:23Z

That all makes sense. Do we have a way to coordinate the updates to psf-salt with updates to the docs, especially with backports involved?

StanFromIreland · 2026-09-01T15:10:08Z

(There's no documented process I'm afraid) You can open a PR there and limit the redirect to specific Python versions. I can review and merge when we land this.

nedbat · 2026-09-02T12:29:49Z

Moving pages causes the "removed HTML IDs" check to fail. The IDs aren't gone, they are in a different page. Do I still add them to removed-ids.txt?

StanFromIreland · 2026-09-02T12:40:20Z

Do I still add them to removed-ids.txt?

Yes, see the line with an asyncio file for the required format.

nedbat · 2026-09-03T17:05:01Z

I've updated the id checker to follow redirect files.

nedbat · 2026-09-04T12:27:40Z

We use sphinxext-rediraffe in the Devguide, it generates stubs with some JS to redirect to the new page.

BTW, the rediraffe stubs do not depend on JavaScript, it uses two techniques:

<html>
    <head>
        <noscript>
            <meta http-equiv="refresh" content="0; url=../builtins/stdtypes.html"/>
        </noscript>
    </head>
    <body>
        <script>
            window.location.href = '../builtins/stdtypes.html' + (window.location.search || '') + (window.location.hash || '');
        </script>
        <p>You should have been redirected.</p>
        <a href="../builtins/stdtypes.html">If not, click here to continue.</a>
    </body>
</html>

though the JavaScript half will keep the anchor and query string.

StanFromIreland · 2026-09-10T19:36:56Z

There are conflicts now.

Also, a few additional sites that need updating:

InternalDocs/structure.md:* [`Doc/library/functions.rst`](../Doc/library/functions.rst)
InternalDocs/structure.md:* [`Doc/library/stdtypes.rst`](../Doc/library/stdtypes.rst)
Tools/unicode/makeunicodedata.py:#   * Doc/library/stdtypes.rst (four occurrences)

nedbat · 2026-09-10T23:19:13Z

I think this is done.

StanFromIreland · 2026-09-11T06:47:06Z

@nedbat can you please avoid force pushing, it makes it a little harder to review. See also the section in the Devguide.

nedbat · 2026-09-11T10:22:20Z

sorry, a habit from other repos.

merwok · 2026-09-11T11:13:23Z

+learning about random subjects, you choose a random page
+and read a section or two.  Regardless of the order in which you
+read the sections of this manual, it helps to first read
+:ref:`built-in-funcs` in :ref:`builtins-index`, as the remainder of this section


Is the second link required, if the first one already brings the reader to the right page?

(This reads to me like «Read Section A in Chapter 1», which is needed in books but not hypertext)

merwok · 2026-09-11T11:14:39Z

+
+.. seealso::

-Let the show begin!


Wasn’t this was harmless and a bit of flair?

merwok · 2026-09-11T11:17:05Z

 browse the table of contents (in front of the manual), or look for a specific
 function, module or term in the index (in the back).  And finally, if you enjoy
-learning about random subjects, you choose a random page number (see module
-:mod:`random`) and read a section or two.  Regardless of the order in which you


Why not keep the random module link as an example of a random page? (and/or maybe a hint about a way to make random decision!)

Not fully sure what the original intent was here, but as we are in Library Reference and not Tutorial I don’t think the link was bad. Can you say why you removed it?

merwok · 2026-09-11T11:18:04Z

-in to the Python interpreter; others are written in Python and imported in
+The Python standard library consists of a collection of modules. There are
+many ways to dissect this collection.  Some modules are written in C and compiled
+into the Python interpreter; others are written in Python and imported in


Should we say that some modules are written in C and compiled to importable modules, or is it confusing at this point?

encukou · 2026-09-11T11:14:36Z

                    self.__ids.add(value)


 def get_ids_from_file(path):


Consider avoiding some duplicate work here:

Suggested change

@functools.cache

def get_ids_from_file(path):

nedbat requested review from AA-Turner, StanFromIreland, hugovk and willingc as code owners August 30, 2026 20:07

bedevere-app Bot added the awaiting core review label Aug 30, 2026

nedbat force-pushed the nedbat/split-builtin-stdlib branch from 37b2ad3 to 10c84e6 Compare August 30, 2026 20:10

nedbat added the skip issue label Aug 30, 2026

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/tools/templates/indexcontent.html Outdated

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/builtin-index.rst Outdated

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/index.rst

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/builtin-index.rst Outdated

nedbat added the skip news label Aug 30, 2026

hugovk reviewed Aug 31, 2026

View reviewed changes

StanFromIreland reviewed Aug 31, 2026

View reviewed changes

Comment thread Doc/reference/index.rst

nedbat added the docs Documentation in the Doc dir label Sep 1, 2026

github-project-automation Bot added this to Docs PRs Sep 1, 2026

github-project-automation Bot moved this to Todo in Docs PRs Sep 1, 2026

nedbat force-pushed the nedbat/split-builtin-stdlib branch from c6de373 to ea9966e Compare September 1, 2026 17:43

nedbat force-pushed the nedbat/split-builtin-stdlib branch from 5219e72 to 373f4e6 Compare September 3, 2026 15:01

nedbat mentioned this pull request Sep 4, 2026

Doc: add anchormap directive for anchor redirects #151113

Closed

StanFromIreland mentioned this pull request Sep 4, 2026

gh-59551: Rename Doc/library/dialog.rst to tkinter.dialogs.rst #151656

Open

StanFromIreland reviewed Sep 10, 2026

View reviewed changes

Comment thread Doc/builtins/index.rst

Comment thread Doc/conf.py Outdated

Comment thread Doc/library/intro.rst Outdated

nedbat added 15 commits September 10, 2026 18:42

Docs: split builtins to their own page from library

a43413e

review feedback

16703c4

addressed Hugo's feedback

92babb2

update the What's Next page

c2dbc6e

one more wording tweak

cb15b64

move builtins to their own directory. fix the reference name

03f29d1

moved pages need to be noted in tools/removed-ids.txt

c28b536

add Python to the builtins reference title

58fa084

add sphinxext-rediraffe for the library->builtins split

45d2eeb

update check-html-ids to handle rediraffe redirects

2be0ba5

now we don't need (page missing) for the redirected pages

5f8e102

update other references to moved pages

d871e32

A seealso from builtins to library

485770d

make a nice section for rediraffe settings

b16e35b

move the builtins note to the end, as a seealso

016ce6b

nedbat force-pushed the nedbat/split-builtin-stdlib branch from 65aaf8b to 016ce6b Compare September 10, 2026 22:42

merwok reviewed Sep 11, 2026

View reviewed changes

encukou approved these changes Sep 11, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Sep 11, 2026

Uh oh!

Uh oh!

Conversation

nedbat commented Aug 30, 2026

Uh oh!

nedbat commented Aug 30, 2026

Uh oh!

StanFromIreland commented Aug 30, 2026

Uh oh!

read-the-docs-community Bot commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nedbat commented Aug 31, 2026

Uh oh!

StanFromIreland commented Aug 31, 2026

Uh oh!

nedbat commented Aug 31, 2026

Uh oh!

StanFromIreland commented Aug 31, 2026

Uh oh!

hugovk commented Sep 1, 2026

Uh oh!

nedbat commented Sep 1, 2026

Uh oh!

StanFromIreland commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nedbat commented Sep 2, 2026

Uh oh!

StanFromIreland commented Sep 2, 2026

Uh oh!

nedbat commented Sep 3, 2026

Uh oh!

nedbat commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland commented Sep 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nedbat commented Sep 10, 2026

Uh oh!

StanFromIreland commented Sep 11, 2026

Uh oh!

nedbat commented Sep 11, 2026

Uh oh!

merwok Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

merwok Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

merwok Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

merwok Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

encukou Sep 11, 2026

read-the-docs-community Bot commented Aug 30, 2026 •

edited

Loading

StanFromIreland commented Sep 1, 2026 •

edited

Loading

nedbat commented Sep 4, 2026 •

edited

Loading